
Super Zelda Editor 
https://sourceforge.net/projects/super-zelda-editor/

Compiled By: Derek McPherson - dmcp2143

Bug Reports and Help Thread
https://www.romhacking.net/forum/index.php?topic=33481.0

Name: SuperZed.exe
Version: 1.035
Date: October 24th, 2021
Size: 891392 bytes (870 KiB)
CRC32: 634E87B0

1. About Super Zelda Editor (SuperZed)
2. About Hyrule Magic (HM)
3. Data Expansion (all dungeon rooms data maxed, plus OW sprites upto 3X original limits)
4. New 16x16 Overworld Editor (edit in 32x32 mode or 16x16, the ultimate tile set control and flexibility)
    - Now with Tiled (www.mapeditor.org) compatibility, Edit Zelda3 OW in The Worlds Best Tile Map Editor
    - For information on using Tiled with SuperZed see "Tiled_tools/readme_z16_tiled.txt"
5. Keyboard Commands (straight from source code)
  a. Dungeon Editor (added a room copy feature)
  b. Overworld Editor (expanded for more sprites. *note entrances and exits are limited still)
6. Changelog
7. Utilities (some helpful open source command line tools I wrote)

#####################
# * Credits/Thanks  #
#####################
Obvious but nesecessary thanks and credit to the Original Hyrule Magic developer(s)
Sephiroth3, MathOnNapkins, Zeldix Community members... 
I think CONN may have written the dungeon sprites jumper ASM to load from another bank than original.
Special thanks to PuzzleDude, whose research AND NOTES on dungeons, pointers and more made all this possible.
Also thanks to XaserLE the author of roomtransfer.cpp whose code helped me along the way.
Thanks to Zarby89 and Scawful for input and bug reports.

Tools used in the creation of SuperZed;
    - Hyrule Magic itself, plus the original source code. (read changesize "p==base[q]")
    - HxD, Hex Editor of Champions
    - VBinDiff, a binary diff tool great for seeing byte by byte changes
    - SNES9X, not a critic of Emulators but this one has been my go to for years
    - Visual Studio 2019, I've always been a huge fan of mingw, but VS debug tools are awesome!
    - MinGW, Used to compile all the c++ command line utilities, many functions started this way
    - Notepad++, Column Editing with HEX numbers is a huge perk, lovely color schemes.
    - MathOnNapkins again for his disassembly documents, came in useful expanding OW sprites.
    - Lunar IPS, Used to create the emptied and expanded IPS ROM patches.
    - KEL CHM Creator, for making the compressed help module SuperZed.chm
    - Lunar Address, Don't even think of ROM hacking if you don't have this tool.
    - Nintendo. I'm a fan of your Zelda games!
            
#####################
# 1. About SuperZed #
#####################
Super Zelda Editor is a complete game editor for SNES The Legend Of Zelda, A Link To The Past (LoZ3 for short)
SuperZed is based upon Hyrule Magic, the original LoZ3 editor. SuperZed has fixed many bugs from HM and has
a few user friendly tweeks and new features that really make it not only more stable but more functional as well.
It is designed to work with expanded ROMs(2MB) that have relocated pointers and data for all 320 dungeon rooms 
out of the base ROM(1stMB) range, but is also able to stay within the original limitations of LoZ3 at 1MB.

Major additions include import/export and a copy room feature for all maps, and a new 16x16 Overworld editor.
For Overworld Tile Maps SuperZed also comes with conversion tools to be compatible with Tiled (www.mapeditor.org)
Some other helpful new features are a Dungeon Entrance 2-click set window, A door position direction type GUI,
The ability to merge parts from one room to another, or create and use prefab dungeon room segments.

Super Zelda Editor is the first LoZ3 editor to draw an entire dungeon rooms contents (all invisible objects
have previously only been visible when selected, one at a time) each object numbered and outlined in a 
unique color depending upon which BG it is a part of. This takes editing LoZ3 to a whole new level, (pun intended) 
now ALL doors and ALL layer objects can be seen, more easily understood, and edited.

#########################
# 2. About Hyrule Magic #
#########################
Lore: HM was originally created by Sephiroth3 2001-2003
HM was kept closed source but released to the public circa 2006? I'm not sure.
After a few years people found plain text source code in the exe, other editors started...
Then eventually the entire source code came out via MathOnNapkins who got permission to improve/open 
source HM. The source code was 1 huge file, a nasty mess indeed but so is ROM hacking.
MON made many improvements, bug fixes and comments, split the code into properly named files, functions 
headers, great work! 
Unfortunately HM had a few major bugs, nothing that didn't get a work around with a HEX editor though. One huge 
drawback was the limitations of space in an original LoZ3 ROM, HM stayed within these limits for the most part
but ROM hackers did not. Along came the process of what came to be known as "HEX GLUING" or Data Expansion.
PuzzleDude is the master of Data Expansion and wrote great documentation that inspired Super Zelda Editor.

#####################
# 3. Data Expansion #
#####################
Data expansion, what's this? Simply put, all of the info was tightly packed in the ROM with hardly any
space for additional data. One needs to delete things in HM to make room for new things, not so with SuperZed.
By relocating dungeons SuperZed makes space for a lot more additional data. The layer objects, sprites, items, 
chests, torches, pits, headers, all dungeon info shifted out of the 1st MB to maximize space. Also SuperZed uses 
the expansion banks for extra overworld space for splitting areas.

SuperZed has a ROM patch with limits moved (or limits can be moved manually in SuperZed if using an original or already 
edited ROM)
SuperZed can load ROMs edited with HM, but SuperZed is not backwards compatible with HM. Format version bumped to 4.
About backwards compatibility. HM uses a generic sprite saving function for both the overworld and dungeons 
that ignores the pointers and writes to the original ROM location, while SuperZed reads the ROM pointers to find 
the moved data anywhere.

*Addendum July 2021: Added the ability to expand Overworld sprites into the space where Dungeon sprite data 
is originally stored. This gave me enough room to nearly triple OW sprite capacity while changing the data 
management from the original tightly packed nintendo method to my style of dedicated space per area saving. 

****************************************
**DANGER!!   IMPORTANT MUST READ!!!!!!**
****************************************
Expanding Dungeon Data can prevent SuperZed from being able to split twinned OW areas.
To prevent this run "Unlock Area Splitting" in the EDIT->General ROM Options menu.
Then split at least 1 overworld twin before moving the dungeon data. 
(edit a twinned area, save it, when prompted "Modify only this area" choose "Yes")

Xpand DNG ____: The edit menu options to expand dungeon data require a CPU hex address 
                   for your desired destination.

               eg. Move Dungeon Headers, enter "108000" to move them into the expanded 
                   extra megabyte, 1 header per room.

Dungeon data locations for szed.ips:
-space reserved for SuperZed overworld expansion-
Headers:           0x140000    - all 320 rooms have unique headers
Chests:            0x142000    - new maximum chests limit 512
Torches:           0x142600    - new maximum torches limit 256
Pushblocks:        0x142800    - new maximum pushblocks limit 256
Damage pits tbl:   0x142A00    - any/all dng rooms can be enabled


Items:             0x148000    - A full bank divided evenly, 32 items/rm
Sprites:           0x150000    - "not so new" ASM code and 32 enemies-sprites/rm
Layers/Rm Objects: 0x158000    - Huge amount of dedicated space (0x800 bytes/rm)
    -note Layers data takes up 320 rooms / 16 rooms per bank = 20 banks 
    -there is free space between rooms for personal ASM use, 
     --it's safe but could be overwriten if editing the dungeon room.
Layers End 0x1F8000 


Expand OW sprites: unlike the other move data options this doesn't take a location for the input, instead it 
takes a mode number. 

0: default rom no expansion (will use classic HM saving, all else use new SaveOWsprites for dedicated pointers

1: basic 3 part expansion
(compatible with alttp, limits raining sprites to 
    estate(4 each) and castle(8), DW 1st & 2nd part share pointers)
                                                                     
2: rain & crystals only, no 1st part sprites 
(for alternate start hacks, skipping pendant collecting phase)

3: balanced 3 part expansion 
(with room for up to 7 rain event sprites everywhere & 8spr 1st & 2nd part LW & DW seperation)


mode 1 is suitable for minor additions through to major hacks that follow similar event structure as alttp 
(13spr per area)

mode 2 is for the common hack trick of skipping the pendant collecting phase, it maximizes sprites per area 
(8 raining/16 2nd part)

mode 3 is for hacks utilizing both more rain state enemies and splitting DW events 
(7 raining/8 1st & 2nd part, LW & DW)

#################################
# 4. New 16x16 Overworld Editor #
#################################
How to edit in 16x16 mode and "compile" a new blockset, new 32x32 tilemaps and insert them all to the ROM for playing, testing, or editing in 32x32 mode again.

Step 1. Using SuperZed run 'Edit->Extract OW Data->Extract All OW Z16 Files'
        - this will write 160 files OW###.z16 to "[SuperZed.exe ROOT]\Maps\"

Step 2. Edit .z16 files with SuperZed by holding "CONTROL" while opening an OW area. Click the 'Exp. Z16' button to save changes to disk.
	    -to be clear, only 1 .z16 file is needed to test the 16x16 editor, it does not save to ROM click exp. Z16 and save edits to disk.
        -to be clear again, all 160 .z16 files are needed to compile a new blockset, and insert matching .z32 files to the game
	    -while in 16x16 mode overlays are not available, but editing other objects is, any changes made will be saved to rom EXCEPT the 16x16 tilemap. 
-Export it.

Step 3. Compiling a new blockset, importing it to rom, and importing the new set of 160 .z32 files
		- It is highly recommended to backup your rom before this process, until you are familiar with how it works.
		- All '/Maps/OW###.z32' files need to be deleted before compiling a new set.

    3.a.) Run SZ16_OW.exe (An external SuperZed tool to handle this heap of data) in the /Maps/ directory. Usage: "SZ16_OW.exe ROM.FILE"
        - SZ16_OW.exe reads all 160 .z16 files and builds a new block set plus 160 new .z32 files, it then imports the new blockset to the rom. (~3 seconds, with text logging)
		- The new .z32 files should be located in "[SuperZed.exe ROOT]\Maps\"   along with the .z16 files and a text log.

	3.b.) Import the new .z32 files that match the new blockset by running;
		- In SuperZed.exe open the new rom, run 'edit->Import OW Data->Import All Z32 files'

* IMPORTANT *
Tile set limit is 8872, running SZ16_OW and hitting the tile limit before finishing reading ALL areas will result in an error output. (and not alter the rom)
Read SZ16_OW-log.txt to see a detailed breakdown of each areas tile count, where the limit was reached if it was, or how many 32x tiles were created if successful. 
Running SZ16_OW.EXE without a ROM file will still build the 32x32 tile list and .z32 tiles for checking the blockset count without touching a rom.


-A consequence of 16x16 OW editing is dramatically changing the 32x32 tileset (obviously)
-I compare 16x16 mode and 32x32 mode like this. 32x32 mode you get a dictionary and lots of words aka tileset and tiles. 16x16 mode you get an alphabet.

    -Pros to 32x32 mode, the game reads this format only, it is a necessary filesize compression design choice made 30+ years ago.
		-you cannot bust the tile limit aka size of dictionary.
		-A single area is only 256 tiles, compared to 1024 in 16x16 mode
    -Cons to 32x32 mode, absolutely mind numbingly awkward to find the tile you want with each 16x16 tile in the right slot. (if it even exists)
		-Changes made to 32x32 tiles can have undesired effects on other areas with different gfx sets

    -Pros to 16x16 mode, flexibility, easily create new 32x32 tilesets without effecting other areas, multiple editors available**
		-Does not alter ROM, can make many changes to any/all 16x16 tilemaps without disturbing the current tileset
		-Always able to save the current editor window because it is to disk, not attempting to squeeze into a new tileset immediately.
			-This is the main advantage to my method, because you can control the 32x32 tileset instead of an editor that sets new tiles on the fly.
			-This means you could design all 160 areas without any concern to tileset count (until compiling back into the game)
		-The .z16 format makes it very easy to shuffle areas, load single areas into quad areas to see how they line up to others and make adjustments.
		-Except for the export and import functions reading from a hardcoded location, the files are "yours" and can be moved/copied/renamed... like any other file.
		-The .z16 format allows for one to make a single empty area (eg. all tile 52 grass) and then clear the entire overworld, with simply copying and renaming a file.
		-Yes, clear the ENTIRE OW, and 32X32 BLOCKSET in a matter of minutes, completely clean slate, or rescue your old hacks Overworld and continue with SuperZed.
    -Cons to 16x16 mode, not supported by game (needs conversion and importing), easy to bust the tile limit with many different 32x32 tiles
        -Small changes in 16x16 mode will result in large changes in the 32x32 tileset, requiring every area to use the new .z32 map files that match this new tileset.
		-4 times as many blocks in any map to edit, some things that become easy and familiar in 32 mode are more clicks here.

known bugs
	- Sometimes SZ16_OW.EXE fails to write to the ROM if .z32 files exist in the folder before running, if so they can all be deleted.


** For information on using Tiled (www.mapeditor.org) to edit the Overworld in 16x16 mode see "Tiled_tools/readme_z16_tiled.txt"

########################
# 5. Keyboard Commands #
########################
%%%%%%%%%%%%%%%%%%%%%%%
% 5.a. Dungeon Editor %
%%%%%%%%%%%%%%%%%%%%%%%
*NOTE* SuperZed emulates the NUMPAD with the top row number keys on the keyboard for laptops, 
both work if a NUMPAD exists.

The Dungeon Editor behaves differently depending on the selected editable choice, bottom right corner 
of the editor. Layers 1 and 2 will work the same just on different things in the room. The doors, sprites, 
items, torches, and blocks editing are all slightly different and will be documented seperatly.

Right clicking with the mouse will bring up options to add and remove things.

%%%%%%%%%%%%%%%
%X Y Z BUTTONS%
%%%%%%%%%%%%%%%
SuperZed has three new buttons in the dungeon editor window. The X Y Z Buttons act as variable
buttons, they do different things depending upon what is currently selected.
Btn|  SELECTION        |  ACTION                               |
---+-------------------+--------------------------------------->
X  |  nothing          |  insert new ? [editing mode]          |
X  |  layer object     |  change object                        |
X  |  door             |  change door type                     |
X  |  chest            |  change object                        |
X  |  sprite           |  change sprite                        |
X  |  item             |  change item                          |
---+-------------------+--------------------------------------->
Y  |  nothing          |  ins. door. set dir/pos, then type    |
Y  |  layer object     |  instant copy                         |
Y  |  door             |  ins. door. set dir/pos, then type    |
Y  |  chest            |  change chest contents                |
Y  |  sprite           |  instant copy                         |
Y  |  item             |  instant copy                         |
---+-------------------+--------------------------------------->
Z  |  nothing          |  N/A                                  |
Z  |  layer object     |  N/A                                  |
Z  |  door             |  N/A                                  |
Z  |  chest            |  change alternate for current content |
Z  |  sprite           |  bg1/bg2 toggle                       |
Z  |  item             |  bg1/bg2 toggle                       |
---V-------------------V---------------------------------------'

%LAYERS%
1st. Room Layer editing, layers are 1, 2. Layer 3 is doors and coming next.
These are all the various tiles in a room including interactables like chests, bottles, etc.
like windows, tables, chairs...
Select an object with the mouse or the left/right arrow keys.
With an object selected move it with mouse dragging or the numpad. 2,4,6,8 down, left, right, up.
Some objects are repeatable or sizeable, "<" or ">" change size, or grab an edge of the object with the mouse 
and drag it to expand/shrink an object. (eg. tables and floor tiles)
Change the tile number of a selected object: "N" -1, "M" +1, "J" - 0x10, "K" + 0x10

%CHESTS%
Select a chest or add one, object F9:9. Change the contents with "+" or "-"
When a chest is selected change the contents with the Y Button, or change the current 
chests contents alternate item with the Z Button.

%DOORS%
Doors. Ugh. Most doors are on layer 3. They are moveable with the numpad.
Doors can be edited the same as other layer objects with N,M,J,K changing door type.

%TORCHES & PUSHBLOCKS%
While selecting a Torch or Pushblock, the numpad will move it (8 directions, diagonals included)
For Torches + button toggles between starting lit or not, - button toggles between bg1 and bg2
For Pushblocks + button toggles the trigger value true or false, - button toggles bg1 and bg2

%SPRITES & ITEMS%
While selecting a sprite or item, you can edit its value with N,M,J,K like above and move 
them in 4 directions with the numpad. Change the selected sprite with the left/right arrows.
Sprite values can be modified with a mouse option to a nice window but items need the keyboard to 
be modified.
Typing numbers (HEX) while editing sprites & items works, awkwardly going over 2 digits is not visible.

%%%%%%%%%%%%%%%%%%%%%%%%%
% 5.b. Overworld Editor %
%%%%%%%%%%%%%%%%%%%%%%%%%
%TILE MAP% (draw/select mode)
Mouse controls all the way. Right click to set the 32x32 block selector (right scrolling window) Draw mode 
left click to set the tile to the current selected 32x32 block... Select mode, left click to draw a rectangle 
and drag it around the tile map to copy paste things. Or select a rectangle hit the copy button and paste it 
into another room.

%SPRITES & ITEMS%
Similar to dungeons... Identical?

%ENTRANCES, EXITS & HOLES%
Right click to add or remove it. Selecting it you can type in the new number (HEX) or increment with N,M,J,K
Exits above 1000 are special markers for the credit screen (they set the scroll start position and tell the 
credits which map to load for each sequence) *note* the scroll direction is hardcoded per credit screen "exit".

################
# 6. CHANGELOG #
################
v1.035 - Oct. 24th 2021
- Added an Overworld Area Select Dialog for use in the Import/Export functions.
- Fixed a bug in "Tiled_tools/TMX_to_Z16.exe" The new utility for converting OW tilemaps from Tiled to SuperZed.

v1.034 - Oct. 22nd 2021
- Set markers checkbox to show in 16x16 mode, they were stuck on and the box was hidden mistakenly.
- Added utilities to create a workflow for editing Overworld Areas in Tiled, the Top Ranked Tile Editor. 
    - See "Tiled_tools/readme_z16_tiled.txt" & www.mapeditor.org

v1.033 - Oct. 12th 2021
- Fixed an error saving large (quad) maps using the "Exp. Z16" button to save to disk.

v1.032 - Oct. 11th 2021
- 16x16 OW tile map editing, hold CONTROL when loading an OW area to edit in 16x16 mode, click the "Exp. Z16" button to save to disk.
- Added .z16 file format, used for import, export, and building new 32x32 OW block sets (8862 limit)
- Doubled width of OW tile selector (8 tiles wide) and added a 16x16 mode to the main selector 
- 16x16 mode tile selector is now also double width, 16 blocks wide and with scrolling.
- Wrote SZ16_OW.EXE (found in /Maps/) the .z16 to .z32 (aka 16x16 to 32x32) complete OW tile set compiler.
- note: SZ16_OW.EXE is an external command line tool designed to give control and flexibility when creating a complete Overworld.

v1.031 - Sept. 30th 2021
- Added Door type names and Object names display text to editor window, dung_object_names will load for customization.
- Added export 32x32 OW tilemap .z32 file, amd autosave for OW tilemaps. Export TM Button on OW editor. [renamed to Exp. Z32](v1.032)
- Added import 32x32 OW tilemap .z32 file. Hold SHIFT when loading a room to load a tilemap from a .z32 file. (All 4x for lg areas)

v1.030 - Sept. 26th 2021
- Fixes in import ZRM file missing chests, and blocks.
- More code cleaning, outline drawing accessed dm_k where it shouldn't have, replaced with local int.

v1.029 - Sept. 20th 2021
- Removed all web links causing false positives on some AV software.
- Various cleaning fixes and started work on overworld area exportor.
- SVN started @ https://sourceforge.net/p/super-zelda-editor/code/

v1.028 - Sept. 17th 2021
- Corrections in object, items, and sprite selection names, and enabled double-clicking to set.
- Added item insert and change dlg for OW.
- Added a check to room 170 limiting sprites there to 5, preventing writing over sprite respawn game code.

v1.027 - Sept. 15th 2021
- X Y buttons for OW editor, an alt. selection window and copy feature for sprites and items like in the Dng. editor.
- Fixed arrow buttons in OW editor broken with v1.026 (slippery fallthrough switch case error on my end)

Sept. 2021  - Released SuperZed v1.025 (First public version, full source released)
            - Fixed an error loading dungeon sprites from ROMs edited with original HM (SZedFrame.c lines 1190, 1191)
                - I left the value hardcoded to original alttp ROM location after some testing.
August 2021 - Added some "button box" windows for alternative selections in dungeons. Eg. Room Select Window.
            - Created the Entrance Setter, and Door dir/pos/type dialogs.
            - Added the X, Y, and Z buttons for variable features depending on editing mode.
            - Fixed the clear all options used to empty a ROM of default data.
                - Retains important data, like  cutscene rooms and Ganons Exit to Triforce Shrine Area.
                - Keeps the abiltiy to edit the ROM after emptying all data without any manual HEX editing.
July   2021 - Rewrote OW sprite saving functions and expanded OW sprite capacity upto 3x original.
            - Fixed a bug that broke the water temple overlay. Simple pointer typo. cba2, where cbb2 is correct.
            - Restored functionality to edit non-expanded roms. 
                - Options are original limits with a 1MB ROM, 
                - original OW areas limits + DNG expansion + optional more OW sprites, 2MB ROM.
                - or with OW area splitting unlocked, Full OW(de-twin OW tilemaps) & DNG expansion 2MB ROM.
            - Fixed a bug that broke secret ow items saving. A measure of the end of that data was off.
            - Finally sorted out the issues with editing whirlpools, flute locations, and exits.
June   2021 - Wrote new search (OW) and Copy room (Dungeon) features.
            - Split World map and OW sprite saving functions.
            - Fixed Dungeon door offsets not writing with the new Dungeon Saveroom function.
            - Made SuperZed.chm the compressed help module, and got SuperZed using it over the outdated WinHelp call
May    2021 - Started work on SuperZed, fixed Overworld Editor issues. (HM used Dungeon data location in its OW save function)
            - Hacked in a *MANDATORY* 2MB ROM size and stopped the horrible filesize clipping bug from original HM.
                - this broke editing a 1MB rom (restored, 210720)
Summer 2020 - Edits of HM to expand dungeon data and work with expanded dungeons. (broke overworld editor)

################
# 7. Utilities # 
################
https://sourceforge.net/p/super-zelda-editor/code/trunk/utilities

2020    - Added command line hex edit, a simple one byte overwriting tool (to log hex edits with a runnable bat file)
2021    - Wrote a very simple, safe and open source ROM expanding utility.
        - Created command line utilities to import/export Dungeons. (superseeded by internal SuperZed tools)
        - A couple of tools to work with different types of binary tables from alttp.
            -Import/Export Data (For hex editing larger data tables with command line tools)
            -Lower Nibble Increaser          - lni.exe 
            -Unsigned Byte Increaser         - ubi.exe
            -Signed Byte Increaser/Decreaser - sbid.exe
        - Wrote block_sum.exe, another simple tool this one for locating empty space in a ROM

Oct 11th, 2021 - SZ16_OW.EXE, an external 'official' SuperZed utiility for converting .z16 to .z32 (aka 16x16 to 32x32) OW area files.
    - This program handles a large amount of data, in a way that is not compatible with being a SuperZed internal function.
	- It is run from the command line "SZ16_OW.EXE ROM.FILE" in the directory with the .z16 files making up the entire OW.
    - Detailed instructions on the process are located above "4. New 16x16 Overworld Editor" 

    - Comments about running this algorithm on the popular rom hacks PW and GOW.
    - GOW: A great hack but with notable OW issues and many areas blanked out. SZ16_OW reduced the tile set to <3000, 5000 free 32x32 tiles available after.
    - PW: A masterful work of 32x32 tile editing using HM. When converted to 16x16 then run through my SZ16_OW algorithm it reduced to 4900 32x32 tiles.

V_1.034 - Tiled tools, Z16 to/from TMX conversion applications. Allowing editing of Zelda3 tile maps in the world leading tile map editor TileEd.
            - See "Tiled_tools/readme_z16_tiled.txt"
        - ZS_to_SZ16.exe see "Samples/ZS_to_SZ16.txt"


     ^      
    ^^^     
   ^^^^^    
  ^     ^   
 ^^^   ^^^  
^^^^^ ^^^^^ 

- SuperZed.exe is written for research and educational purposes.
